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Express.js 中 文 文档 


来 源 : Express.js 中 文 文档 


新 手指 南 


开始 


在 确认 已 经 安装 了 node 之 后 (下 载 ), 在 你 的 机 器 上 创建 一 个 目录 ， 让 我 们 来 开始 你 
的 第 一 个 应 用 程序 吧 


$ mkdir hello-world 


在 这 个 目录 中 你 首先 得 定义 一 下 你 的 应 用 程序 “ 包 ” 文 件 ， 它 和 其 它 的 node 程 序 包 是 
一 样 的 。 你 得 在 这 个 目录 中 创建 一 个 package.json 文 件 ， 在 里 面 express 作 为 一 个 
Kei. 你 也 可 以 使 用 npm info express version 来 获取 express 最 新 的 版 本 

号 ， 最 好 使 用 最 新 的 版 本 号 而 不 是 下 面 的 3.x， 这 样 新 出 的 功能 就 不 会 让 你 感觉 到 


奇怪 了 。 
{ 
"name": "hello-world", 
"description": "hello world test app", 
"version": "0.0.1", 


"private": true, 
"dependencies": { 
"express": "3.x" 


现在 package.json 文 件 已 经 准备 好 了 ， 使 用 npm(1) 安装 依赖 ， 这 里 的 依赖 仅仅 
是 Express。 


$ npm install 


当 npm 完 成 后 ，Express 3.x 和 它 的 依赖 就 安装 到 你 的 .jnode_modules 目录 里 了 。 
你 可 以 通过 npm ls 来 确认 一 下 ， 它 会 把 Express 和 它 的 依赖 展示 成 下 面 的 树 状 
结构 。 


$ npm ls 
hello-world@0.0.1 /private/tmp 
حا‎ expressQ3.0.0beta7 
م‎ commander@0.6.1 
r connect@2.3.9 
م‎ bytes@0.1.0 
| 一 cookie@0.0.4 
I— 0 
I— formidable@1.0.11 
L— qs@0.4.2 
cookieQ0.0.3 
debug@0.7.0 
freshQ0.1.0 
methods@0.0.1 
mkdirp@0.3.3 
range-parser@0.0.4 
response-send@0.0.1 
ا‎ 0 
ا‎ 3 
L— 6 


TT 


现在 我 们 来 写真 正 的 代码 了 ! 创建 一 个 名 为 app.js 或 者 server.js 的 文件 ， 叫 什么 看 
你 个 人 喜好 了 。 S Aexpress 然后 使 用 代码 express() 创建 一 个 新 的 应 用 程序 : 


var express = require('express'); 
var app = express(); 


在 这 个 应 用 程序 实例 里 ， 你 可 以 通过 app.VERB() 定义 路 由 ， 下 面 的 例子 是 "GET 
/返回 "Hello World" 字符 串 。 req 和 res 对 象 是 和 node 原 生 提 供给 你 的 一 致 
的 ， 你 也 可 以 执行 res.pipe() , req.on('data', callback) 等 任何 事情 在 没 
有 Express 的 情况 下 可 以 做 的 事情 。 


Express 给 这 些 对 象 加 了 一 个 封装 好 的 方法 ， 上 比如 res.send() ， 它 会 帮 你 设置 
Content-Length: 


app.get('/hello.txt', function(req, res){ 
res.send('Hello World'); 
3); 


现在 我 们 通过 执行 app.listen() 来 绑 定 并 监听 连接 。 它 接受 的 参数 和 
nodenet.Server#listen() 的 方法 一 致 : 


var server = app.listen(3000, function() { 
console.log('Listening on port %d', server.address().port); 


3); 


使 用 express(1) 来 生成 一 个 应 用 程序 
Express 团 队 维 护 了 一 个 可 以 快速 生成 项 目 模板 的 可 执行 文件 ， 这 里 命名 为 
express(1) . 如 果 你 使 用 npm 全 局 安装 的 express-generator 在 你 的 机 器 任何 位 
它 都 是 可 用 的 : 


$ npm install -g express-generator 


这 个 工具 提供 了 一 个 非常 简单 的 生成 一 个 程序 骨架 的 功能 ， 但 是 它 也 有 局 限 ， 比 如 
它 只 支持 很 少 的 几 个 模板 引擎 。 而 事实 上 Express 几 乎 支持 所 有 的 为 node 所 建 的 模 
板 引 擎 。 使 用 --help 查看 一 下 帮助 : 


Usage: express [options] 


Options: 
-h, --help 输出 帮助 信息 
-V, --version 输出 版 本 号 
-e, --ejs 添加 ejs 模板 引擎 支持 (SUA jade) 
-H, --hogan 添加 hogan. js 模板 引擎 支持 
-C, --css «engine» 样式 < 引擎 > 支持 (less|stylus) (默认 为 css ) 
-f，--force 强制 在 非 空 目 录 执 行 </engine> 


如 果 你 想 生 成 一 个 支持 Jade, Stylus 的 应 用 程序 ， 只 需要 简单 的 执行 下 面 的 命令 


$ express --sessions --css stylus --ejs myapp 


create : myapp 

create : myapp/package.json 
create : myapp/app.js 

create : myapp/public 

create : myapp/public/javascripts 
create : myapp/public/images 
create : myapp/public/stylesheets 
create : myapp/public/stylesheets/style.styl 
create : myapp/routes 

create : myapp/routes/index.js 
create : myapp/views 

create : myapp/views/index. jade 
create : myapp/views/layout. jade 


install dependencies: 
$ cd myapp && npm install 


run the app: 
$ DEBUG=myapp node app 


和 其 它 node 程 序 一 样 ， 你 必须 安装 依赖 : 


$ cd myapp 
$ npm install 


然后 让 我 们 运行 它 吧 ! 


$ node app 


这 些 就 是 一 个 简单 的 应 用 程序 创建 和 运行 的 所 有 步骤 。 记 住 Express 没 有 限定 任何 
的 目录 结构 ， 这 只 是 一 个 方便 你 工作 的 基本 结构 。 如 果 你 想得到 更 多 怎么 组 织 目录 
结构 选择 ， 可 以 查看 github 上 的 示例 。 


错误 处 理 


错误 处 理 的 中 间 件 和 普通 的 中 间 件 定义 是 一 样 的 ， 只 是 它 必须 有 4 个 形 参 ， 这 是 它 
的 形式 : (err, reg, res, next) : 


app.use(function(err, req, res, next)( 
console.error(err.stack); 
res.send(500, 'Something broke!'); 


3); 


一 般 来 说 非 强制 性 的 错误 处 理 一 般 被 定义 在 最 后 ， 下 面 的 代码 展示 的 就 是 放 在 别 的 
app.use() 之 后 : 


app.use(express.bodyParser()); 

app.use(express.methodOverride()); 

app.use(app.router); 

app.use(function(err, req, res, next)( 
// logic 

3): 


在 这 些 中 间 件 里 的 响应 是 可 以 任意 定义 的 。 只 要 你 喜欢 ， 你 可 以 返回 任意 的 内 容 ， 
譬如 HTML 页 面 , 一 个 简单 的 消息 ， 或 者 一 个 JSON 字 符 串 。 


对 于 一 些 组 织 或 者 更 高 层次 的 框架 ， 你 可 能 会 像 定义 普通 的 中 间 件 一 样 定义 一 些 错 
误 义理 的 中 间 件 。 假设 你 想 定 义 一 个 中 间 件 区 别 对 待 通过 XHR 和 其 它 请 求 的 错误 处 
理 ， 你 可 以 这 么 做 : 


app.use(express.bodyParser()); 
app.use(express.methodOverride()); 
app.use(app.router); 
app.use(logErrors); 
app.use(clientErrorHandler); 
app.use(errorHandler); 


通常 logErrors 用 来 纪录 诸如 stderr loggly, 或 者 类 似 服 务 的 错误 信息 : 


function logErrors(err, reg, res, next) { 
console.error(err.stack); 
next(err); 


clientErrorHandler 定义 如 下 ， 注 意 错误 非常 明确 的 向 后 了 。 


function clientErrorHandler(err, req, res, next) { 
if (req.xhr) { 
res.send(500, ( error: ‘Something blew up!' }); 
) else { 
next(err); 
j 
j 


下 面 的 errorHandler "捕获 所 有 " 的 异常 ， 定义 为 : 


function errorHandler(err, reg, res, next) 1 
res.status(500); 
res.render('error', { error: err }); 


j 


在 线 用 户 计 数 


这 一 小 节 我 们 讲解 一 个 小 而 全 的 应 用 程序 ， 它 通过 Redis 记 录 在 线 用 户 数 。 首先 你 
需要 创建 一 | json 文件 ， 包 含 两 个 依赖 一 个 是 redis 客户 端 ， 另 一 个 是 
Express。 需要 确认 你 安装 了 redis, 可 以 能 过 执行 $ redis-server 来 确认 : 


"name" : "app" P 
"version": "0.0.1", 
"dependencies": { 
"express": "3.x", 
"redis": nx 
J 
} 


接 下 来 你 需要 你 创建 一 个 应 用 程序 ， 和 一 个 redis 连 接 : 


var express = require('express'); 
var redis = require('redis'); 

var db = redis.createClient(); 
var app = express(); 


接 下 来 是 纪录 用 户 在 线 的 中 间 件 。 这 里 我 们 使 用 sorted sets, 它 的 一 个 好 处 是 我 们 
可 以 查询 最 近 N 窜 秒 内 在 线 的 用 户 。 我 们 通过 传人 一 个 时 间 惟 来 当 作 成 员 
的 "score"。 注意 我 们 使 用 User-Agent 作为 一 个 标识 用 户 的 id。 


app.use(function(req, res, next){ 
var ua = req.headers['user-agent']; 
db.zadd('online', Date.now(), ua, next); 


3): 


下 一 个 中 间 件 是 通过 zrevrangebyscore 来 查询 上 一 分 钟 在 线 用 户 。 我 们 将 能 得 到 
从 当前 时 间 算 起 在 60,000 毫 秒 内 活路 的 用 户 。 


app.use(function(req, res, next){ 
var min = 60 * 1000; 
var ago - Date.now() - min; 
db.zrevrangebyscore('online', '-«inf', ago, function(err, users){ 
if (err) return next(err); 
req.online - users; 
next(); 
3); 
3); 


gb Bg 


最 后 我 们 来 使 用 它 ， 绑 定 到 一 个 端口 ! 这 些 就 是 这 个 程序 的 一 切 了 ， 在 不 同 的 浏览 
器 里 访问 这 个 应 用 程序 ， 你 会 看 到 计数 的 增长 。 


app.get('/', function(req, res)( 
res.send(req.online.length + ' users online'); 


3); 


app.listen(3000); 


给 Express 加 一 层 代理 


在 Express 的 前 端 使 用 一 个 反 向 代理 ， 比 如 Varnish 或 者 Nginx 是 非常 常见 的 , 它 不 

需要 额外 的 配置 。 在 通过 app.enable('trust proxy') 激活 了 "trust proxy" 设置 
ls, Express 就 会 知道 它 在 一 个 代理 的 后 面 ， X-Forwarded-* 必须 被 信任 ， 通 

常情 况 下 这 些 头 是 很 容易 被 伪装 的 。 


使 用 了 这 个 设置 后 会 有 一 些 很 棒 的 小 变化 。 首先 由 代理 设置 
的 x-Forwarded-Proto 会 告诉 程序 它 是 https 还 是 http 。 这 个 值 会 影响 
req.protocol. 


第 二 个 变化 是 req.ip 和 req.ips 的 值 会 被 X-Forwarded-For 列表 里 的 地 址 取代 。 


调试 Express 


Express 使 用 debug 模块 来 输出 信息 。 如 果 想 看 到 这 些 信 息 ， 可 以 在 运行 你 的 程序 
时 设置 DEBUG 环境 变量 为 express:* ,调试 信息 会 输出 在 终端 里 。 


$ DEBUG=express:* node app.js 
使 用 上 面 的 方式 运行 hello world 的 例子 ， 将 会 输出 下 面 的 内 容 


express:application booting in development mode +5 
express:router defined get /hello.txt +5 
express:router defined get /hello.txt +1ms 


获取 更 多 关于 debug 的 信息 ， 可 以 查看 debug 文档 


问答 


怎样 定义 模型 ? 


Express 根本 没有 涉及 到 数据 库 ， 这 个 任务 留 给 了 第 三 方 的 node 模 块 ， 有 了 第 三 方 
的 模块 基本 上 可 以 与 任何 数据 库 交 互 


怎样 做 用 户 认 证 ? 
这 是 另 一 个 Express 不 会 做 的 事情 ， 你 可 以 使 用 任何 你 想 用 的 认证 方案 ， 这 里 有 一 
个 简单 的 例子 。 


Express 支持 哪个 模板 引擎 ? 


任何 遵守 这 样 回调 的 (path, locals, callback) .为 了 统一 模板 引擎 接口 和 组 
存 ， 推 荐 查看 consolidate.js 寻找 帮助 . 有 些 没 有 列 出 来 的 模板 引擎 没准 也 支持 


Express. 


我 应 该 怎样 组 织 我 的 程序 结构 ? 

事实 上 这 个 没有 一 个 标准 答案 ， 这 与 你 的 程序 规模 和 团队 强烈 相关 。 为 了 尽 可 能 的 
灵活 ，Express 没 有 规定 程序 的 结构 

你 可 以 把 路 由 和 其 它 的 一 些 程序 特定 的 逻辑 代码 以 任意 的 目录 结构 任意 数量 的 文件 
存放 。 查看 下 面 的 例子 找 点 灵感 


Route listings 

Route map 

Route bootstrapping 
MVC style controllers 


已 经 存在 的 简化 这 些 模式 的 第 三 方 Express 扩 展 : 


e Resourceful routing 
e Namespaced routing 


我 应 该 怎样 从 多 个 目录 提供 静态 文件 服务 ? 


你 可 以 会 在 你 的 程序 中 多 次 使 用 任意 一 个 中 间 件 。 使 用 下 面 的 方式 ， 当 你 请 
求 "GET /javascripts/jquery.js" 时 ， 会 先 检查 "./public/javascripts/jquery.js", 如 果 它 
不 存在 ， 随 后 的 中 间 件 会 检查 "./files/javascripts/jquery.js". 


app.use(express.static('public')); 
app.use(express.static('files')); 


怎样 在 提供 静态 文件 服务 的 时 候 加 一 个 前 级 路 径 名 ? 


Connect's 的 中 间 件 绑 定 技术 人 允许 你 指定 一 个 路 径 名 前 级, 一 个 常用 的 例子 是 你 可 以 
前 级 一 个 根本 不 是 请 求 路 径 中 一 部 分 的 字符 。 假设 你 要 请 求 "GET 
Ifiles/javascripts/jquery.js", 你 可 以 把 中 间 件 挂 在 "/files", 暴露 出 
"javascripts/jquery.js" 作 为 req.url 来 让 中 间 件 为 这 个 文件 提供 服务 : 


app.use('/public', express.static('public')); 


怎么 迁移 Express 2.x 应 用 程序 ? 


Express 2x 甚 至 能 支持 到 node 1.0, 所 以 可 能 没有 必要 由 于 Express 3x 的 重 构 和 API 
改变 就 迁移 ， 如 果 你 对 2x 感 觉 良 好 ， 那 就 停留 在 那个 版 本 上 。 真 的 要 迁移 可 以 看 这 
里 或 者 查看 一 下 3.x 的 改动 列表 


怎么 处 理 404s? 


在 Express 里 404s 不 被 认为 是 出 错 的 结果 ， 所 以 错误 处 理 中 间 件 不 会 捕获 404s, 这 是 
因为 一 个 404 只 是 由 于 有 一 些 额 外 的 工作 没有 做 ， 换 而 言 之 ，Express 已 经 执行 了 所 
有 的 中 间 件 / 路 由 分 发 ， 然 而 没有 发 现 有 返回 。 你 所 要 做 的 仅仅 是 在 代码 底部 加 一 
个 中 间 件 去 处 理 没有 返回 的 情况 ， 并 且 手 动 返 回 一 个 404 


app.use(function(req, res, next){ 
res.send(404, 'Sorry cant find that!'); 
3); 


Express 里 怎样 处 理 异常 ? 


4 个 ， 它 们 定义 如 下 (err, reg, res, next) : 


app.use(function(err, req, res, next){ 
console.error(err.stack); 
res.send(500, 'Something broke!'); 


1:05 
查看 错误 义理 , 获取 更 多 信息 


怎样 输出 纯 HTML 文 件 ? 


不 要 这 么 做 ! 根本 没有 必要 直接 使 用 res.render() 输出 HTML 文 件 , 如 果 你 有 一 
个 特定 的 文件 应 该 使 用 res.sendfile() ,如 果 你 要 使 用 一 个 目录 里 大 量 的 静态 资 
源 提供 服务 ， 请 使 用 express.static() 中 间 件 . 


Express 的 代码 库 有 多 大 ? 


Express 是 一 个 非常 小 的 框架 ，3.0.0 正 式 发 布 版 只 有 932 行 源码 ，Express 强 烈 依赖 
的 Connect 只 有 267 行 源码 ，Connect 可 选 的 中 间 件 和 扩展 总 共 1143 行 源码 ， 并 且 只 
有 到 使 用 时 才 会 加 载 


API 参考 


express() 


创建 一 个 express 应 用 程序 


var express = require('express'); 
var app = express(); 


app.get('/', function(req, res){ 
res.send('hello world'); 
3); 


app.listen(3000); 


Application 


app.set(name, value) 
ism name 的 值 设 为 ”value 
app.set('title', 'My Site'); 
app.get('title'); 
// => "My Site" 
app.get(name) 


获取 设置 项 name 的 值 


app.get('title'); 
// => undefined 


app.set('title', 'My Site'); 


app.get('title'); 
// => "My Site" 


app.enable(name) 


将 设置 项 name 的 值 设 为 true. 


app.enable('trust proxy'); 
app.get('trust proxy'); 
// => true 


app.disable(name) 


将 设置 项 name 的 值 设 为 false. 


app.disable('trust proxy'); 
app.get('trust proxy'); 
// => false 


app.enabled(name) 


检查 设置 项 name 是否 已 启用 


app.enabled('trust proxy'); 
// => false 


app.enable('trust proxy'); 
app.enabled('trust proxy'); 
// => true 


app.disabled(name) 
检查 设置 项 name 是 否 已 禁 


app.disabled('trust proxy'); 
// => true 


app.enable('trust proxy'); 
app.disabled('trust proxy'); 
// => false 


app.configure([env], callback) 


“4 env 和 app.get('env') (也 就 是 process.env.NODE_ENV ) 匹配 时 , 调 

用 callback 。 保 留 这 个 方法 是 出 于 历史 原因 ， 后 面 列 出 的 if 语句 的 代码 其 实 
更 加 高 效 、 直 接 。 使 用 app.set() 配合 其 它 一 些 配置 方法 后 ,没有 必要 再 使 用 这 个 
方法 。 


// 所 有 环境 

app.configure(function(){ 
app.set('title', 'My Application'); 

3) 


// 开发 环境 
app.configure('development', function()( 
app.set('db uri', 'localhost/dev'); 


}) 
// 只 用 于 生产 环境 


app.configure('production', function(){ 
app.set('db uri', 'n.n.n.n/prod'); 
3) 


更 高 效 且 直 接 的 代码 如 下 : 


// 所 有 环境 
app.set('title', 'My Application'); 


// 只 用 于 开发 环境 


if ('development' == app.get('env')) 1 
app.set('db uri', 'localhost/dev'); 


// 只 用 于 生产 环境 
if ('production' == app.get('env')) 1 
app.set('db uri', 'n.n.n.n/prod'); 


app.use([path], function) 
使 用 中 间 件 function ,可 选 参数 path 默认 为 "/"。 


var express = require('express'); 
var app = express(); 


// 一 个 简单 的 logger 

app.use(function(req, res, next){ 
console.log('%s %s', req.method, req.url); 
next(); 


}); 


// 响应 
app.use(function(req, res, next){ 
res.send('Hello World'); 


}); 


app.listen(3000); 


圭 载 的 路 径 不 会 在 req 里 出 现 ， 对 中 间 件 function 不 可 见 ， 这 意味 着 你 
在 function 的 回调 参数 req 里 找 不 到 path。 这 么 设计 的 为 了 让 间 件 可 以 在 不 需要 
更 改 代 码 就 在 任意 "前 级 "路 径 下 执行 


这 里 有 一 个 实际 应 用 场景 ， 常 见 的 一 个 应 用 是 使 用 ./public 提 供 静 态 文件 服务 ， 用 
express.static() 中 间 件 : 


// GET /javascripts/jquery.js 

// GET /style.css 

// GET /favicon.ico 
app.use(express.static(__dirname + '/public')); 


如 果 你 想 把 所 有 的 静态 文件 路 径 都 前 级 "/static", 你 可 以 使 用 “ 挂 载 " 功 能 。 如 

R req.url 不 包含 这 个 前 级 , 挂 载 过 的 中 间 件 不 会 执行 。 当 function 被 执行 的 

时 候 , 这 个 参数 不 会 被 传递 。 这 个 只 会 影响 这 个 函数 ， 后 面 的 中 间 件 里 得 到 的 
req.url 里 将 会 包含 Vstatic" 


// GET /static/javascripts/jquery.js 

// GET /static/style.css 

// GET /static/favicon.ico 

app.use('/static', express.static(__dirname + '/public')); 


使 用 app.use() “定义 的 "中 间 件 的 顺序 非常 重要 ， 它 们 将 会 顺序 执行 ，use 的 先 
后 顺序 决定 了 中 间 件 的 优先 级 。 比如 说 通常 express.logger() 是 最 先 使 用 的 
一 个 组 件 ， 纪 录 每 一 个 请 求 


app.use(express.logger()); 
app.use(express.static(__dirname + '/public')); 
app.use(function(req, res){ 

res.send('Hello'); 


}); 


如 果 你 想 忽略 请 求 静 态 文件 的 纪录 ， 但 是 对 于 在 logger() 之 后 定义 的 路 由 和 中 
间 件 想 继 续 纪 录 ， 只 需要 简单 的 把 static() 移 到 前 面 就 行 了 : 


app.use(express.static(__dirname + '/public')); 
app.use(express.logger()); 
app.use(function(req, res){ 

res.send('Hello'); 


F)? 


另 一 个 现实 的 例子 ， 有 可 能 从 多 个 目录 提供 静态 文件 服务 ， 下 面 的 例子 中 会 优先 
从 "./public" 目 录取 文件 


app.use(express.static(__dirname + '/public')); 
app.use(express.static(__dirname + '/files')); 
app.use(express.static(__dirname + '/uploads')); 


settings 


下 面 的 内 建 的 可 以 改变 Express 行 为 的 设置 


env 运行 时 环境 ， 默 认为 process.env.NODE ENV 或 者 "development" 
trust proxy 激活 反 向 代理 ， 黑 认 未 激活 状态 

jsonp callback name 修改 默认 ?callback- 的 jsonp 回 调 的 名 字 

json replacer JSON replacer 替换 时 的 回调 , 默认 为 null 

json spaces JSON 响应 的 空格 数量 ， 开 发 环境 下 是 2 ,生产 环境 是 0 
case sensitive routing 路 由 的 大 小 写 敏 感 , 默认 是 关闭 状态 ， "/Foo" 

和 "/foo" 是 一 样 的 

e strict routing 路 由 的 严格 格式 , 默认 情况 下 "foo" 和 "/foo/" 是 被 同样 对 
待 的 

e view cache 模板 缓存 ， 在 生产 环境 中 是 默认 开启 的 

e view engine 模板 引擎 

e views 模板 的 目录 , 默认 是 "process.cwd() + ./views" 


app.engine(ext, callback) 


注册 模板 引擎 的 callback 用 来 处 理 ext 扩展 名 的 文件 默认 情况 下 , 根据 文件 扩 
展 名 require() 对 应 的 模板 引擎 。 比如 你 想 泻 染 一 个 "foo.jade" 文件 ，Express 
会 在 内 部 执行 下 面 的 代码 ， 然 后 会 缓存 require() ， 这 样 就 可 以 提高 后 面 操 作 的 


app.engine('jade', require('jade'). express); 


那些 没有 提供 . ^ express 的 或 者 你 想 泻 染 一 个 文件 的 扩展 名 与 模板 引擎 默认 的 
不 一 致 的 时 候 ， 也 可 以 用 这 个 方法 。 比如 你 想 用 EJS 模 板 引 擎 来 处 理 ".html" 后 级 
的 文件 : 


app.engine('html', require('ejs').renderFile); 


这 个 例子 中 EJS 提 供 了 一 个 .renderFile() 方法 和 Express 预 期 的 格式 : 
(path, options, callback) 一 致 , 可 以 在 内 部 给 这 个 方法 取 一 个 别 
名 ejs. express ， 这 样 你 就 可 以 使 用 ".ejs" 扩展 而 不 需要 做 任何 改动 


有 些 模板 引擎 没有 遵循 这 种 转换 ， 这 里 有 一 个 小 项 目 consolidate.js 专门 把 所 有 的 
node 流 行 的 模板 引擎 进行 了 包装 ， 这 样 它们 在 Express 内 部 看 起 来 就 一 样 了 。 


var engines = require('consolidate'); 
app.engine('haml', engines.haml); 
app.engine('html', engines.hogan); 


app.param([name], callback) 


PEERS HE: ee, thay :user 出 现在 一 个 路 由 路 径 中 ， 你 也 许 会 自动 载 信 
加 载 用 户 的 逻辑 ， 并 把 它 放置 到 req.user ,或 者 校 验 一 下 输入 的 参数 是 否 正 
Tf. 


下 面 的 代码 片段 展示 了 callback 很 像 中 间 件 ， 但 是 在 参数 里 多 加 了 一 个 值 ， 这 里 
名 为 id . 它 会 党 试 加 载 用 户 信息 ， 然 后 赋值 给 req.user ,否则 就 传递 错 
误 next(err) . 


app.param('user', function(reg, res, next, id){ 
User.find(id, function(err, user){ 

if (err) { 
next(err); 

} else if (user) { 
req.user = user; 
next(); 

) else 1 
next(new Error('failed to load user')); 


另外 你 也 可 以 只 传 一 个 callback ,这样 你 就 有 机 会 改变 app.param() API. tt 
如 express-params 定 义 了 下 面 的 回调 ， 这 个 允许 你 使 用 一 个 给 定 的 正则 去 限制 参 


o 


下 面 的 这 个 例子 有 一 点 点 高 级 ， 检 查 如 果 第 二 个 参数 是 一 个 正则 ， 返 回 一 个 很 像 上 
面 的 "user" 参 数 例 子 行为 的 回调 函数 。 


app.param(function(name, fn){ 
if (fn instanceof RegExp) { 
return function(req, res, next, val){ 
var captures; 
if (captures = fn.exec(String(val))) (1 
req.params[name] - captures; 
next(); 
} else { 
next('route'); 


0 
这 个 图 数 现在 可 以 非常 有 效 的 用 来 校 验 人 参数， 或 者 提供 正则 捕获 后 的 分 组 。 


app.param('id', /^\d+$/); 


app.get('/user/:id', function(req, res)( 
res.send('user ' + req.params.id); 


3): 
app.param('range', /^(Nw*)N.N.(Nw*)?$/); 


app.get('/range/:range', function(req, res){ 
var range - req.params.range; 
res.send('from ' + range[1] + ' to ' + range[2]); 


3): 


app.VERB(path, [callback...], callback) 


app.VERB() 方法 为 Express 提 供 路 由 方法 , VERB 是 指 某 一 个 HTTP 动作 , 比如 
app.post() 。 可 以 提供 多 个 callbacks, 这 多 个 callbacks 都 将 会 被 平等 对 待 ， 它 
们 的 行为 跟 中 间 件 一 样 ， 也 有 一 个 例外 的 情况 ， 如 果 某 一 个 callback 执 行 

了 next('route') ， 它 后 面 的 callback 就 被 忽略 。 这 种 情形 会 点 用 在 当 满 足 一 个 
路 由 前 级 ， 但 是 不 需要 义理 这 个 路 由 ， 于 是 把 它 向 后 传递 。 


下 面 的 代码 片段 展示 最 简单 的 路 由 定义 。Express 会 把 路 径 字 符 串 转 为 正则 表达 
式 ， 然 后 在 符合 规则 的 请 求 到 达 时 立即 使 用 。 请 求 参 数 不 会 被 考虑 进来 ， 比 如 
"GET "会 匹配 下 面 的 这 个 路 由 , 而 "GET /?name=tobi" 同 样 也 会 匹配 。 


app.get('/', function(req, res){ 
res.send('hello world'); 


3): 


同 祥 也 可 以 使 用 正则 表达 式 ， 并 且 它 能 够 在 你 指定 特定 路 径 的 时 候 发 挥 大 作用 。 He 
如 下 面 的 例子 可 以 匹配 "GET /commits/71dbb9c", 同时 也 能 匹配 "GET 
/commits/7 1dbb9c..4c084f9". 


app.get(/^N/commitsN/(Nw*)(?:N.N. (Nw*))?$/, function(req, res){ 
var from - req.params[0]; 
var to - req.params[1] || 'HEAD'; 
res.send('commit range ' + from + '..' + to); 


3): 


可 以 传递 一 些 回 调 ， 这 对 复 用 一 些 加 载 资 源 、 校 验 的 中 间 件 很 有 用 。 


app.get('/user/:id', user.load, function(){ 
IO 
3) 


这 些 回 调 同样 可 以 通过 数组 传递 ， 简 单 的 放置 在 数组 中 即 可 。 


var middleware = [loadForum, loadThread]; 


app.get('/forum/:fid/thread/:tid', middleware, function(){ 
iP MUS 
3) 


app.post('/forum/:fid/thread/:tid', middleware, function(){ 
A/ 
}) 


app.all(path, [callback...], callback) 


这 个 方法 很 像 app.vERB() ,但 是 它 匹 配 所 有 的 HTTP 动 作 


这 个 方法 在 给 特定 前 级 路 径 或 者 任意 路 径 上 处 理 时 会 特别 有 用 。 比如 你 想 把 下 面 的 
路 由 放 在 所 有 其 它 路 由 之 前 ， 它 需要 所 有 从 这 个 路 由 开始 的 加 载 验证 ， 并 且 自 动 加 
载 一 个 用 户 记 住 所 有 的 回调 都 不 应 该 被 当 作 终点 ， loadUser 能 够 被 当 作 一 个 任 
务 ， 然 后 next() 去 匹配 接 下 来 的 路 由 。 


app.all('*', requireAuthentication, loadUser); 


Or the equivalent: 


app.all('*', requireAuthentication) 
app.all('*', loadUser); 


ATER RMF Ie ESSERE USE REA-—MIFRAI—MER, 2218 
fl AU ZR 77 "api": 


app.all('/api/*', requireAuthentication); 


app.locals 


应 用 程序 本 地 变量 会 附加 给 所 有 的 在 这 个 应 用 程序 内 泻 染 的 模板 。 这 是 一 个 非常 有 
FRAUEN, RAR 用 程序 级 数据 一 样 。 


app.locals.title = 'My App'; 
app.locals.strftime = require('strftime'); 


app.locals 对 象 是 一 个 JavaScript Function , 执行 的 时 候 它 会 把 属性 合并 到 
它 自身 ， 提 供 了 一 种 简单 展示 已 有 对 象 作为 本 地 变量 的 方法 


app.locals({ 
title: 'My App’, 
phone: '1-250-858-9990', 
email: 'me@myapp.com' 
3); 
app.locals.title 
// => 'My App' 


app.locals.email 
// => 'meQmyapp.com' 


app.locals 对 象 最 终 会 是 一 个 JavaScript 函 数 对 象 ， 你 不 可 以 使 用 Functions 和 
Objects 内 置 的 属性 ， 上 比 


如 name, apply, bind, call, arguments, length, constructor 


app.locals({name: 'My App'}); 


app.locals.name 
// => 返回 'app.locals' 而 不 是 'My App' (app.locals 是 一 个 函数 !) 
// => 如 果 name 变 量 用 在 一 个 模板 里 ， 发 返回 一 个 ReferenceError 


全 部 的 保留 字 列 表 可 以 在 很 多 规范 里 找到 。 JavaScript 规范 介绍 了 原来 的 属性 ， 
有 一 些 还 会 被 现代 的 JS 引擎 识别 ，EcmaScript 规范 在 它 的 基础 上 ， 统 一 了 值 ， 添 
加 了 一 些 ， 删 除了 一 些 废弃 的 。 如 果 感 兴趣 ， 可 以 看 看 Functions 和 Objects 的 属性 
值 。 


默认 情况 下 Express 只 有 一 个 应 用 程序 级 本 地 变量 ， 它 是 settings. 


app.set('title', 'My App'); 
// 在 view 里 使 用 settings.title 


app.render(view, [options], callback) 


^N ص‎ 


泻 染 view, callback 用 来 处 理 返 回 的 泻 染 后 的 字符 串 。 这 个 是 
res.render() 的 应 用 程序 级 版 本 ， 它 们 的 行为 是 一 样 的 。 
app.render('email', function(err, html){ 

3); 
app.render('email', { name: 'Tobi' }, function(err, html){ 


3); 


app.routes 


app.routes 对 象 存储 了 所 有 的 被 HTTP verb E 3LER EH, 这 个 对 象 可 以 用 在 一 些 

内 部 功能 上 ， 比 如 Express 不 信用 它 来 做 路 由 分 发 ， 同 时 在 没 

有 app.options() 定义 的 情况 下 用 它 来 处 理 默认 的 <string>OPTIONS</string> 行 

人 
目的。 


console.log(app.routes) 


{ get: 
[ { path: '/', 
method: 'get', 
callbacks: [Object], 
keys: [], 
regexp: /^N/N/?$/i }, 
{ path: '/user/:id', 
method: 'get', 
callbacks: [Object], 
keys: [{ name: 'id', optional: false }], 
regexp: /A\/user\/(?: ([A\/]+?))\/?$/1 } J, 
delete: 
[ { path: '/user/:id', 
method: 'delete', 
callbacks: [Object], 
keys: [Object], 
regexp: /A\/user\/(?: ([A\/]+?))\/7?$/1i } ] ) 


app.listen() 
在 给 定 的 主机 和 端口 上 监听 请 求 ， 这 个 和 node 的 文档 http.Server#listen() 是 一 致 的 


var express = require('express'); 
var app = express(); 
app.listen(3000); 


express() 返回 的 app 实际 上 是 一 个 JavaScript Function , 它 被 设计 为 传 给 
node 的 http servers 作 为 处 理 请 求 的 回调 画 数 。 因 为 app 不 是 从 HTTP 或 者 HTTPS 
继承 来 的 ， 它 只 是 一 个 简单 的 回调 画 数 ， 你 可 以 以 同一 份 代码 同时 处 理 HTTP and 
HTTPS 版 本 的 服务 。 


var express = require('express'); 
var https = require('https'); 

var http = require('http'); 

var app = express(); 


http.createServer(app).listen(80); 
https.createServer(options, app).listen(443); 


app.listen() 方法 只 是 一 个 快捷 方法 ， 如 果 你 想 使 用 HTTPS， 或 者 同时 提供 
HTTP 和 HTTPS， 可 以 使 用 上 面 的 代码 


app.listen = function(){ 
var server = http.createServer(this); 
return server.listen.apply(server, arguments); 


Fo 


Request 


req.params 


这 是 一 个 数组 对 象 ， 命 名 过 的 参数 会 以 键 值 对 的 形式 存放 。 比如 你 有 一 个 路 
由 /user/:name , "name" 属 性 会 存放 在 req.params.name . 这 个 对 象 默 认为 
0١ 


// GET /user/tj 
req.params.name 
// => jS 


当 使 用 正则 表达 式 定义 路 由 的 时 候 ， req.params[N] 会 是 这 个 应 用 这 个 正则 后 的 
捕获 分 组 ，N 是 代表 的 是 第 N 个 捕获 分 组 。 这 个 规则 同样 适用 于 全 匹配 的 路 由 ， 如 
pallii 


// GET /file/javascripts/jquery.js 
req.params[0] 
// => "javascripts/jquery.js" 


req.query 
这 是 一 个 解析 过 的 请 求 参 数 对 象 ， 黑 认为 {} . 


// GET /search?q=tobitferret 


req.query.q 
// => "tobi ferret" 


// GET /shoes?order=desc&shoe[ color ]=blue&shoe[ type ]=converse 
req.query.order 
// => "desc" 


req.query.shoe.color 
// => "blue" 


req.query.shoe.type 
// => "converse" 


req.body 


这 个 对 应 的 是 解析 过 的 请 求 体 。 这 个 特性 是 bodyParser() 中 间 件 提供 ,其 它 的 请 
求 体 解析 中 间 件 可 以 放 在 这 个 中 间 件 之 后 。 当 bodyParser() 中 间 件 使 用 后 ， 这 
个 对 象 默认 为 {} 。 


// POST user[name]-tobi&user [email]-tobiQlearnboost.com 
req.body.user.name 
// => "tobi" 


req.body.user.email 
// => "tobiQlearnboost.com" 


// POST { "name": "tobi" } 
req.body.name 
// => "tobi" 


req.files 


这 是 上 传 的 文件 的 对 象 。 这 个 特性 是 bodyParser() 中 间 件 提供 ,其 它 的 请 求 体 解 
析 中 间 件 可 以 放 在 这 个 中 间 件 之 后 。 当 bodyParser() 中 间 件 使 用 后 ， 这 个 对 象 
默认 为 0e 


例如 file 字段 被 命名 为 "image", 当 一 个 文件 上 传 完 成 后 ， req.files.image 将 会 
包含 下 面 的 File 对 象 : 


{ size: 74643, 
path: '/tmp/8ef9c52abe857867fd0a4e9a819d1876', 
name: 'edge.png', 
type: 'image/png', 
hash: false, 
lastModifiedDate: Thu Aug 09 2012 20:07:51 GMT-0700 (PDT), 
_writeStream: 
{ path: '/tmp/8ef9c52abe857867fd0a4e9a819d1876', 
150: 1 
writable: false, 
flags: 'w', 
encoding: 'binary', 
mode: 438, 
bytesWritten: 74643, 
busy: false, 
queue: [], 
.open: [Function], 
drainable: true }, 
length: [Getter], 
filename: [Getter], 
mime: [Getter] } 


bodyParser() 中 间 件 是 在 内 部 使 用 node-formidable 来 处 理 文件 请 求 ， 所 以 接收 
的 参数 是 一 致 的 。 举 个 例子 ， 使 用 formidable 的 选项 keepExtensions , € EA 
false , 在 上 面 的 例子 可 以 看 到 给 出 的 文件 

名 "/tmp/8ef9c52abe857867fd0a4e9a819d1876" 不 包含 ".png" 扩展 名 . 为 了 让 它 可 
以 保留 扩展 名 ， 你 可 以 把 参数 传 给 bodyParser() : 


app.use(express.bodyParser({ keepExtensions: true, uploadDir: '/my, 


«j = 





req.param(name) 


返回 name 参数 的 值 。 


// ?Name=tobi 
req.param('name' ) 
// => "tobi" 


// POST name=tobi 
req.param('name' ) 
// => "tobi" 


// /user/tobi for /user/:name 
req.param('name' ) 
// => "tobi" 


查找 的 优先 级 如 下 : 


© req.params 
e req.body 
e req.query 


直接 访问 req.body , req.params ,和 req.query 应 该 更 合适 ， 除 非 你 真 的 
需要 从 这 几 个 对 象 里 同时 接受 输入 。 


req.route 
这 个 对 象 里 是 当前 匹配 的 Route 里 包含 的 属性 ， 比 如 原始 路 径 字 符 串 ， 产 生 的 正 
则 ， 等 等 


app.get('/user/:id?', function(req, res){ 
console.log(req.route); 


3): 


上 面 代码 的 一 个 输出 : 





{ path: '/user/:id?', 
method: 'get', 
callbacks: [ [Function] ], 
keys: [ { name: 'id', optional: true } |], 
regexp: /^N/user(?:N/([^N/]*?))?N/?$/i, 
params: [ id: '12' ] } 


req.cookies 


当 使 用 cookieParser() 中 间 件 之 后 ， 这 个 对 象 默 认为 {} ， 它 也 包含 了 用 户 代 
理 传 过 来 的 cookies。 


// Cookie: name=tj 
req.cookies.name 
// => neg 


req.signedCookies 


cookieParser(secret) 中 间 件 后 ， 这 个 对 象 默认 为 O ,否则 包含 了‏ 83 5 فلا 

用 户 代理 传 回来 的 签名 后 的 cookie， 并 等 待 使 用 。 签 名 后 的 cookies 被 放 在 一 个 单独 
的 对 象 里 ， 恶 意 攻 击 者 可 以 很 简单 的 蔡 换 掉 req.cookie 的 值 。 需 要 注意 的 是 签 

名 的 cookie 不 代表 它 是 隐藏 的 或 者 加 密 的 ， 这 个 只 是 简单 的 阻止 自 改 cookie。 


// Cookie: user-tobi.CP7AWaXDf AKIRfHA49dQzKJx7sKzzSoPq'7/ACBBRVw1IS3 
req.signedCookies.user 
// => “tobi” 


到 二 = 一 = 
req.get(field) 


获取 请 求 关 里 的 field 的 值 ， 大 小 写 不 敏感 . Referrer 和 Referer 字段 是 可 以 互 换 
的 。 


req.get( Content-Type ); 
// => "text/plain" 


req.get( 'content-type'); 
// => "text/plain" 


req.get('Something!'); 
// => undefined 


别名 为 req.header(field) . 


req.accepts(types) 


. 检查 给 定 的 types 是 不 是 可 以 接受 类 型 ， 当 可 以 接受 时 返回 最 匹配 的 ， 否 则 返 
回 undefined - 这 个 时 候 你 应 该 响应 一 个 406 "Not Acceptable". 


type 的 值 可 能 是 单一 的 一 个 mime 类 型 字符 串 , 比 如 "application/json", 扩展 名 
为 "json", 也 可 以 为 逗号 分 隔 的 列表 或 者 数组 。 当 给 定 的 是 数组 或 者 列表 ， 返 回 最 佳 
匹配 的 。 


// Accept: text/html 
req.accepts('html'); 
// => "html" 


// Accept: text/*, application/json 
req.accepts('html'); 

// => "html" 
req.accepts('text/html'); 

// => "text/html" 
req.accepts('json, text'); 

// => "json" 
req.accepts('application/json'); 

// => "application/json" 


// Accept: text/*, application/json 
req.accepts('image/png'); 
req.accepts('png'); 

// -» undefined 


// Accept: text/*;q-.5, application/json 
req.accepts(['html', 'json']); 
req.accepts('html, json'); 

// => "json" 


req.accepted 


返回 一 个 从 高 质量 到 低 质量 排序 的 接受 媒体 类 型 数组 


[ { value: 'application/json', 
quality: 1, 
type: 'application', 
subtype: 'json' Jj, 

{ value: 'text/html', 
quality: 0.5, 
type: 'text', 
subtype: 'html' } ] 


req.is(type) 


检查 请 求 的 文件 头 是 不 是 包含 "Content-Type" 字段 , 它 匹配 给 定 的 type . 


// With Content-Type: text/html; charset=utf-8 
req.is('html'); 

req.is('text/html' ); 

req.is('text/*"); 

// => true 

// When Content-Type is application/json 
req.is('json'); 

req.is('application/json'); 
req.is('application/*'); 

// -» true 


req.is('html'); 
// => false 


req.ip 
返回 远程 地 址 ， 或 者 当 “ 信 任 代理 "使 用 时 ， 返 回 上 一 级 的 地 址 


req.ip 
JE c EO ke 


req.ips 

当 设 置 "trust proxy" 4 true 时 , 解析 "X-Forwarded-For" 里 的 ip 地 址 列表 ， 并 返回 
一 个 数组 否则 返回 一 个 空 数组 举 个 例子 ， 如 果 "X-Forwarded-For" 的 值 为 "client， 
proxy1, proxy2" 你 将 会 得 到 数组 ["client", "proxyi", "proxy2"] 这 里 可 以 
看 到 "proxy2" 是 最 近 一 个 使 用 的 代理 

req.path 


返回 请 求 的 URL 的 路 径 名 
// example.com/users?sort=desc 
req.path 
// => "/users" 

req.host 


返回 从 "Host" 请 求 头 里 取 的 主机 名 ,不 包含 端口 号 。 


// Host: "example.com:3000" 
req.host 
// => "example.com" 


req.fresh 


判断 请 求 是 不 是 新 的 -通过 对 Last-Modified 或 者 ETag 进行 匹配 , 来 标明 这 个 资源 是 
不 是 "新 的 ". 


req.fresh 
// => true 


req.stale 
判断 请 求 是 不 是 旧 的 -如 果 Last-Modified 或 者 ETag 不 匹配 , 标明 这 个 资源 是 " 旧 的 ". 


Check if the request is stale - aka Last-Modified and/or the ETag do not match, 
indicating that the resource is "stale". 


req.stale 
// => true 
req.xhr 


Jr; SK جو‎ 88 E A"X-Requested-With" ix 4 عد رام‎ FF Ba 77 "XMLHttpRequest", 
jQuery 等 库 发 请 求 时 会 设置 这 个 头 


req.xhr 
// => true 


req.protocol 
返回 标识 请 求 协 议 的 字符 串 ， 一 般 是 "http"， 当 用 TLS 请 求 的 时 候 是 "https"。 


当 "trust proxy" 设置 被 激活 ， "X-Forwarded-Proto" 头 部 字段 会 被 信任 。 如 果 你 使 
用 了 一 个 支持 https 的 反 向 代理 ， 那 这 个 可 能 是 激活 的 。 


req.protocol 
// => "http" 


req.secure 


检查 TLS 连接 是 否 已 经 建立 。 这 是 下 面 的 缩写 : 


'https' == req.protocol; 


req.subdomains 


把 子 域 当 作 一 个 数组 返回 


// Host: "tobi.ferrets.example.com" 

req.subdomains 

// => ["ferrets", "tobi"] 
req.originalUrl 
这 个 属性 很 像 req.url ,但 是 它 保 留 了 原始 的 url。 这 样 你 在 做 内 部 路 由 的 时 候 可 
DBS req.url 。 比如 app.use() 的 挂 载 功 能 会 重 写 req.url ， 把 从 它 挂 载 的 点 
开始 


// GET /search?q=something 
req.originalUrl 
// => "/search?q=something" 


req.acceptedLanguages 


返回 一 个 从 高 质量 到 低 质量 排序 的 接受 语言 数组 


Accept-Language: en;q=.5, en-us 
// => ['en-us', 'en'] 


req.acceptedCharsets 


返回 一 个 从 高 质量 到 低 质量 排序 的 可 接受 的 字符 集 数 组 


Accept-Charset: iso-8859-5;q=.2, unicode-1-1;q-0.8 
// -» ['unicode-1-1', 'iso-8859-5'] 


req.acceptsCharset(charset) 


检查 给 定 的 charset 是 不 是 可 以 接受 的 


req.acceptsLanguage(lang) 


BEATEN lang 是 不 是 可 以 接受 的 
Response 
res.status(code) 


支持 链 式 调用 的 node's res.statusCode= . 


res.status(404).sendfile('path/to/404.png'); 


res.set(field, [value]) 
设置 响应 头 字 段 field 4H value , 也 可 以 一 次 传人 一 个 对 象 设 置 多 个 值 。 
res.set('Content-Type', 'text/plain'); 
res.set({ 
'Content-Type': 'text/plain', 
'Content-Length': '123', 


"Eladg 2) 93451 
}) 


res.header(field, [value]) 的 别名 。 


res.get(field) 
返回 一 个 大 小 写 不 敏感 的 响应 头 里 的 field 的 值 


res.get('Content-Type'); 
// => "text/plain" 


res.cookie(name, value, [options]) 


设置 cookie name {4H value , 接受 字符 串 参 数 或 者 JSON 对 象 。 path RIEF 
认为 "T. 


res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin 
res.cookie('rememberme', '1', ( expires: new Date(Date.now() + 90060) 


‘| — B 








maxAge 属性 是 一 个 便利 的 设置 "expires", 它 是 一 个 从 当前 时 间 算 起 的 毫秒 。 下 面 
的 代码 和 上 一 个 例子 中 的 第 二 行 是 同样 的 作用 。 


res.cookie('rememberme', '1', ( maxAge: 900000, httpOnly: true Jj) 


»] 





«| c 


可 以 传 一 个 序列 化 的 JSON 对 象 作 为 参数 ， 它 会 自动 被 bodyParser() 中 间 件 解 
析 。 


res.cookie('cart', { items: [1,2,3] }); 
res.cookie('cart', { items: [1,2,3] }, { maxAge: 900000 }); 


这 个 方法 也 支持 签名 的 cookies。 只 需要 简单 的 传递 signed SR, 
res.cookie() 会 使 用 通过 express.cookieParser(secret) 传 入 的 secret 来 
签名 这 个 值 


res.cookie('name', 'tobi', { signed: true }); 


稍 后 你 就 可 以 通过 req.signedCookie 对 象 访问 到 这 个 值 。 


res.clearCookie(name, [options]) 


把 name 的 cookie 清 除 . path 参数 默认 为 /". 


res.cookie('name', 'tobi', { path: '/admin' }); 
res.clearCookie('name', { path: '/admin' }); 


res.redirect([status], url) 


使 用 可 选 的 状态 码 跳 转 到 url KA status 默认 为 302 "Found". 


res.redirect('/foo/bar'); 
res.redirect('http://example.com'); 
res.redirect(301, 'http://example.com'); 
res.redirect('../login'); 


Express 支 持 几 种 跳 转 ， 第 一 种 便 是 使 用 一 个 完整 的 URI 跳 转 到 一 个 完全 不 同 的 网 
站 。 


res.redirect('http://google.com'); 





第 二 种 是 相对 根 域 路 径 跳 转 ， 比 如 你 现在 在 
http://example.com/admin/post/new , 下 面 的 的 代码 跳 转 到 /admin 将 会 把 
你 带 到 http://example.com/admin 


res.redirect('/admin'); 


这 是 一 种 相对 于 应 用 程序 挂 载 点 的 跳 转 。 比如 把 一 个 blog 程 序 挂 在 /blog , 事实 
上 它 无 法 知道 它 被 挂 载 ， 所 以 当 你 使 用 跳 转 /admin/post/new 时 ， 将 到 跳 

到 http://example.com/admin/post/new ,下 面 的 相对 于 挂 载 点 的 跳 转 会 把 你 带 
到 http://example.com/blog/admin/post/new : 


res.redirect('admin/post/new'); 


路 径 名 . 跳 转 同样 也 是 支持 的 。 比如 你 
在 http://example.com/admin/post/new , 下面 的 跳 转 会 把 你 带 到 
http//example.com/admin/post 


res.redirect('..'); 


最 后 也 是 最 特别 的 跳 转 是 back 跳 转 , 它 会 把 你 带 回 Referer (也 有 可 能 是 
Referrer) 的 地 址 当 Referer 丢 失 的 时 候 默 认为 / 


res.redirect('back'); 


res.location 
设置 location 请 求 头 . 


res.location('/foo/bar'); 
res.location('foo/bar'); 
res.location('http://example.com'); 
res.location('../login'); 
res.location('back'); 


可 以 使 用 与 res.redirect() 里 相同 的 urls o 


举 个 例子 ， 如 果 你 的 程序 根 地 址 是 /blog ,下面 的 代码 会 把 location 请 求 头 设 
置 为 /blog/admin : 


res.location('admin' ) 


res.charset 


设置 字符 集 。 默 认为 "utf-8"。 


res.charset = 'value'; 
res.send('some html'); 
// -» Content-Type: text/html; charset-value 


res.send([body|status], [body]) 
发 送 一 个 响应 。 


res.send(new Buffer('whoop')); 

res.send(( some: 'json' 3); 

res.send('some html'); 

res.send(404, 'Sorry, we cannot find that!'); 
res.send(500, ( error: 'something blew up' }); 
res.send(200); 


这 个 方法 在 输出 non-streaming 响 应 的 时 候 自 动 完 成 了 大 量 有 用 的 任务 比如 如 果 在 
它 前 面 没 有 定义 Content-Length, 它 会 自动 设置 ; 比如 加 一 些 自动 的 HEAD; 比如 对 
HTTP 缓 存 的 支持 . 


当 参 数 为 一 个 Buffer 时 Content-Type 会 被 设置 为 "application/octet-stream" IR 
非 它 之 前 有 像 下 面 的 代码 : 


res.set('Content-Type', 'text/html'); 
res.send(new Buffer('some html')); 


当 参 数 为 一 个 String 时 Content-Type ERA i E 77 "text/html": 


res.send('some html'); 


当 参 数 为 Array 或 者 Object 时 Express 会 返回 一 个 JSON: 


res.send(( user: 'tobi' }) 
res.send([1,2,3]) 


最 后 一 条 当 一 个 Number 作为 参数 ， 并 且 没 有 上 面 提 到 的 任何 一 条 在 响应 体 里 ， 
Express 会 帮 你 设置 一 个 响应 体 比如 200 会 返回 字符 "OK", 404 会 返回 "Not 
Found" 等 等 . 


res.send(200) 
res.send(204) 
res.send(500) 


res.json([status|body], [body]) 


返回 一 个 JSON 响应 。 当 res.send() 的 参数 是 一 个 对 象 或 者 数组 的 时 候 ， 会 
调用 这 个 方法 。 当然 它 也 在 复杂 的 空 值 (null, undefined, etc)JSON 转 换 的 时 候 很 有 
用 ， 因为 规范 上 这 些 对 象 不 是 合法 的 JSON。 


res.json(null) 
res.json(( user: 'tobi' }) 
res.json(500, { error: 'message' }) 


res.jsonp([status|body], [body]) 


返回 一 个 支持 JSONP 的 JSON 响 应 。 Send a JSON response with JSONP support. 
这 个 方法 同样 使 用 了 res.json() ,只 是 加 了 一 个 可 以 自 定义 的 JSONP 回调 支 
持 。 


res.jsonp(null) 
// -» null 


res.jsonp(( user: 'tobi' }) 
// => ( "user": "tobi" } 


res.jsonp(500, ( error: 'message' }) 


// => { "error": "message" } 


默认 情况 下 JSONP 回调 的 函数 名 就 是 callback 。 你 可 以 通过 jsonp callback 
name 来 修改 这 个 值 。 下 面 是 一 些 使 用 JSONP 的 例子 。 


// ?callback-foo 
res.jsonp(( user: 'tobi' }) 
// => foo({ "user": "tobi" }) 


app.set('jsonp callback name', 'cb'); 


// ?cb-foo 
res.jsonp(500, ( error: 'message' }) 
// => foo(( "error": "message" }) 


res.type(type) 


设置 Sets the Content-Type to the mime lookup of type , or when "/" is present 
the Content-Type is simply set to this literal value. 


res.type('.html'); 
res.type('html'); 
res.type('json'); 
res.type('application/json'); 
res.type('png'); 


res.contentType(type) 方法 的 别名 。 


res.format(object) 


置 特定 请 求 关 的 响应 。 这 个 方法 使 用 req.accepted , 这 是 一 个 通过 质量 值 作 
Dae 的 数组 ， 第 一 个 回调 会 被 执行 。 当 没 有 匹配 时 ， 服 务 器 返回 一 个 
406 "Not Acceptable", 或 者 执行 default 回调 


Content-Type 在 callback 被 选中 执行 的 时 候 会 被 设置 好 , 如 果 你 想 改变 它 ， 可 以 在 
callback 内 使 用 res.set() 或 者 res.type() 


下 面 的 例子 展示 了 在 请 求 头 设置 为 "application/json" 或 者 /son' 的 时 候 会 返 
E] { "message": "hey" } 如 果 设 置 的 是 人 " 那么 所 有 的 返回 都 将 是 "hey" 


res.format(( 
'text/plain': function(){ 
res.send('hey'); 


ty 


'text/html': function(){ 
res.send('hey'); 


ty 


'application/json': function(){ 
res.send(( message: 'hey' }); 


} 
3): 


除了 使 用 标准 的 MIME 类 型 ， 你 也 可 以 使 用 扩展 名 来 映射 这 些 类 型 下 面 是 一 个 不 太 
完整 的 实现 : 


res.format({ 
text: function(){ 
res.send('hey'); 


ty 


html: function(){ 
res.send('hey'); 


ty 


json: function(){ 
res.send(( message: 'hey' }); 


} 
2r 


res.attachment([filename]) 


设置 响应 头 的 Content-Disposition 字段 值 为 "attachment". WRA filename ع2‎ 
数 ，Content-Type 将 会 依据 文件 扩展 名 通过 res.type() 自动 设置 , 并 且 Content- 
Disposition 的 "filename=" 参 数 将 会 被 设置 


res.attachment(); 
// Content-Disposition: attachment 


res.attachment( 'path/to/1logo.png'); 


// Content-Disposition: attachment; filename="logo.png" 
// Content-Type: image/png 


res.sendfile(path, [options], [fn]]) 
path 所 传输 附件 的 路 径 。 


它 会 根据 文件 的 扩展 名 自动 设置 响应 头 里 的 Content-Type 字 段 。 [B0 78 ER 
数 fn(err) 在 传输 完成 或 者 发 生 错误 时 会 被 调用 执行 。 


Options: 


e maxAge 毫秒 ， 黑 认为 0 
e root 文件 相对 的 路 径 


这 个 方法 可 以 非常 良好 的 支持 有 缩 上 略图 的 文件 服务 。 


app.get('/user/:uid/photos/:file', function(req, res){ 
var uid = req.params.uid 
file = req.params.file; 
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req.user.mayViewFilesFrom(uid, function(yes) { 


if (yes) { 
res.sendfile('/uploads/' + uid + '/' + file); 
) else { 
res.send(403, 'Sorry! you cant see that.'); 
} 
3); 
3): 


res.download(path, [filename], [fn]) 


path 所 需 传输 附件 的 路 径 ， 通常 情况 下 浏览 器 会 弹出 一 个 下 载 文 件 的 窗口 。 浏 
览 器 弹出 框 里 的 文件 名 和 响应 头 里 的 Disposition "filename=" 参数 是 一 致 的 , 你 也 可 
以 通过 传人 filename 来 自由 设置 。 


当 在 传输 的 过 程 中 发 生 一 个 错误 时 ， 可 选 的 回调 函数 fn 会 被 调用 执行 。 这 个 方 
法 使 用 res.sendfile() 传 输 文 件 。 


res.download('/report-12345.pdf'); 
res.download('/report-12345.pdf', 'report.pdf'); 


res.download('/report-12345.pdf', 'report.pdf', function(err){ 
if (err) 1 
// 义理 错误 ， 请 牢记 可 能 只 有 部 分 内 容 被 传输 ， 所 以 
// 检查 一 下 res.headerSent 
) else { 
// 减少 下 载 的 积分 值 之 类 的 
} 
}); 


res.links(links) 


合并 给 定 的 links ,并 且 设 置 给 响应 头 里 的 "Link" FER. 


res. links({ 
next: 'http://api.example.com/users?page-2', 
last: 'http://api.example.com/users?page-5' 


3); 


转换 后 : 


Link: <http://api.example.com/users?page=2>; rel="next", 
<http://api.example.com/users?page=5>; rel="last" 


res.locals 


在 某 一 次 请 求 范围 下 的 响应 体 的 本 地 变量 ， 只 对 此 次 请 求 期 间 的 views 可 见 。 另外 
这 个 API 其 实 和 app.locals 是 一 样 的 . 


这 个 对 象 在 放置 请 求 级 信息 时 非常 有 用 ， 比 如 放置 请 求 的 路 径 名 ， 验 证 过 的 用 户 ， 
用 户 设置 等 等 


app.use(function(req, res, next){ 
res.locals.user - req.user; 
res.locals.authenticated = ! req.user.anonymous; 
next( ); 


3); 


res.render(view, [locals], callback) 


泻 染 view ,同时 向 callback 传人 泻 染 后 的 字符 串 。 callbackZ RTA, BH 

会 把 泻 染 后 的 字符 串 输 出 至 请 求 方 ， 一 般 如 果 不 需 要 再 对 泻 染 后 的 模板 作 操作 ， 就 
REE callback, 当 有 错误 发 生 时 next(err) 会 被 执行 . 如 果 提 供 了 callback 参 
数 ， 可 能 发 生 的 错误 和 泻 染 的 字符 串 都 会 被 当 作 参 数 传人 , 并 且 没 有 默认 响应 。 


res.render('index', function(err, html){ 
rp qute 
3); 


res.render('user', { name: 'Tobi' }, function(err, html){ 
"PA TS 
3); 


Middleware 


basicAuth() 


基本 的 认证 中 间 件 ， 在 reg.user 里 添加 用 户 名 
用 户 名 和 密码 的 例子 : 


app.use(express.basicAuth('username', 'password')); 


校 验 回调 : 


app.use(express.basicAuth(function(user, pass)( 
return 'tj' -- user && 'wahoo' -- pass; 


})); 


SH 
X 


验 接受 参数 fn(err, user) ,下 面 的 例子 req.user 将 会 作为 User 对 象 传 


app.use(connect.basicAuth(function(user, pass, fn){ 
User.authenticate({ user: user, pass: pass }, fn); 


3)) 


bodyParser() 


支持 JSON, urlencoded 和 multipart requests 的 请 求 体 解析 中 间 件 。 这 个 中 间 件 
是 json() , urlencoded() ,和 multipart() 这 几 个 中 间 件 的 简单 封装 


app.use(express.bodyParser()); 


// 等 同 于 : 
app.use(express.json()); 
app.use(express.urlencoded()); 
app.use(express.multipart()); 


从 安全 上 考虑 ， 如 果 你 的 应 用 程序 不 需要 文件 上 传 功 能 ， 最 好 关闭 它 。 我 们 只 使 用 
我 们 需要 的 中 间 件 。 例 如 : 我 们 不 使 用 bodyParser 、 multipart() 这 两 个 中 
间 件 。 


app.use(express.json()); 
app.use(express.urlencoded()); 


如 果 你 的 应 用 程序 需要 使 用 文件 上 传 ， 设 置 一 下 就 行 。 一 个 简单 的 介绍 如 何 使 用 . 


compress() 


通过 gzip / deflate 压 缩 响 应 数据 . 这 个 中 间 件 应 该 放置 在 所 有 的 中 间 件 最 前 面 以 保证 
所 有 的 返回 都 是 被 压缩 的 


app.use(express.logger()); 
app.use(express.compress()); 
app.use(express.methodOverride()); 
app.use(express.bodyParser()); 


cookieParser() 


解析 请 求 头 里 的 Cookie, 并 用 cookie 名 字 的 键 值 对 形式 放 在 req.cookies 你 也 可 
以 通过 传递 一 个 secret 字符 串 激活 签名 了 的 cookie 


app.use(express.cookieParser()); 
app.use(express.cookieParser('some secret')); 


cookieSession() 


提供 一 个 以 cookie 为 基础 的 sessions, 设置 在 req.session 里 。 这 个 中 间 件 有 以 
下 几 个 选项 : 


e key cookie 的 名 字 ， 上 默认 是 connect.sess 
e secret prevents cookie tampering 
e cookie session cookie 设置 , 默认 是 
{ path: '/', httpOnly: true, maxAge: null } 
e proxy 当 设 置 安全 cookies 时 信任 反 向 代理 (通过 "x-forwarded-proto") 


app.use(express.cookieSession()); 


清 掉 一 个 cookie, 只 需要 在 响应 前 把 null 赋 值 绘 session: 


req.session = null 


csrf() 


CSRF 防护 中 间 件 

默认 情况 下 这 个 中 间 件 会 产生 一 个 名 为 ”csrf" 的 标志 ， 这 个 标志 应 该 添加 到 那些 需 
要 服务 器 更 改 的 请 求 里 ， 可 以 放 在 一 个 表单 的 隐藏 域 ， 请 求 参数 等 。 这 个 标志 可 以 
通过 req.csrfToken() 方法 进行 校 验 。 


bodyParser() 中 间 件 产生 的 req.body , query() 产生 的 req.query ,请 求 
头 里 的 "X-CSRF-Token" 是 默认 的 value 画 数 检查 的 项 


这 个 中 间 件 需要 session 支 持 ， 因 此 它 的 代码 应 该 放 在 session() 之 后 . 


directory() 
文件 夹 服务 中 间 件 ， 用 path 提供 服务 。 


app.use(express.directory('public' )) 
app.use(express.static('public')) 


这 个 中 间 件 接收 如 下 参数 : 


e hidden 显示 隐藏 文件 ， 默 认为 false. 
e icons 显示 图 标 ， 默 认为 false. 
e filter 人 在 文件 上 应 用 这 个 过 滤 辑 数 。 默 认为 false. 


Jade 文档 


Jade 是 一 个 高 性 能 的 模板 引擎 ， 它 深 受 Haml 影 响 ， 它 是 用 javascript 实 现 的 ,并 且 可 
以 供 node 使 用 . 


翻译 : 草 依 山 翻译 反馈 Fork me 


di 
HE 


客户 端 支持 
代码 高 可 读 
灵活 的 缩 进 
块 展 开 
混合 
静态 包含 
属性 改写 
安全 ， 默 认 代 码 是 转 义 的 
运行 时 和 编译 时 上 下 文 错 误 报告 
命令 行 下 编译 jade 模 板 
html 5 模式 (使 用 山 5 文 档 类 型 ) 
在 内 存 中 缓存 (可 选 ) 
可 以 通过 filters 修改 树 
模板 继承 
原生 支持 Express JS 
通过 each 枚 举 对 象 、 数 组 甚至 是 不 能 枚 举 的 对 象 
块 注释 
没有 前 级 的 标签 
AST filters 
o :Sass 必须 已 经 安装 sass.js 
o ‘less 必须 已 经 安装 less.js 
o :markdown 必须 已 经 安装 markdown-js 或 者 node-discount 
o :cdata 
o :coffeescript 必须 已 经 安装 coffee-script 
Vim Syntax 
TextMate Bundle 
Screencasts 
html2jade 444% 25 


npm install jade 


浏览 器 支持 
把 jade 编 译 为 一 个 可 供 浏览 器 使 用 的 单 文件 ， 只 需要 简单 的 执行 : 


$ make jade.js 


如 果 你 已 pe npm install uglify-js )， 你 可 以 执行 下 面 的 命令 它 
会 生成 所 有 的 文件 。 其 实 每 一 个 正式 版 本 里 都 帮 你 做 了 这 事 。 


$ make jade.min.js 


默认 情况 下 ， o املاع وي‎ __.lineno = 3 的 行 
号 的 形式 。 在 浏览 器 里 使 用 的 时 候 ， 你 可 以 通过 传递 一 
项 { compileDebug: false } 来 去 掉 这 个 。 كك‎ 


Hello #{name}‏ م 


ABUSO HEB FAI : 


function anonymous(locals, attrs, escape, rethrow) { 
var buf - []; 
with (locals || (3) 1 
var interp; 
buf.push('\n<p>Hello ' + escape((interp = name) == null ? '' 


return buf.join(""); 





通过 使 用 Jade 的 ./runtime.js 你 可 以 在 浏览 器 使 用 这 些 预 编译 的 模板 而 不 需要 
使 用 Jade, 你 只 需要 使 用 runtime.js 里 的 工具 函数 , 它们 会 放 在 jade.attrs , 
jade.escape 这 些 里 。 把 选项 { client: true ) 传递 给 


jade.compile() , Jade &iüix BAS BRAIS AAE jade.attrs , 
jade.escape . 


function anonymous(locals, attrs, escape, rethrow) { 
var attrs = jade.attrs, escape = jade.escape, rethrow = jade.rett 
var buf = []; 
with (locals || {}) 1 
var interp; 
buf.push('\n<p>Hello ' + escape((interp = name) == null 2 '' 


return buf.join(""); 





了‏ لكر 
公开 API‏ 


var jade = require('jade'); 


// Compile a function 
var fn = jade.compile('string of jade', options); 
fn(locals); 


e self 使 用 self 命名 空间 来 持 有 本 地 变量 . 默认 为 fa/se 
e locals 本 地 变量 对 象 

e filename 异常 发 生 时 使 用 ，includes 时 必需 

e debug 输出 token 和 翻译 后 的 函数 体 

e compiler 蔡 换 掉 jade 默 认 的 编译 器 

e compileDebug false 的 时 候 调 斌 的 结构 不 会 被 输出 
语法 

行 结束 标志 


CRLF 和 CR 会 在 编译 之 前 被 转换 为 LF 
标签 
标签 就 是 一 个 简单 的 单词 : 


html 


它 会 被 转换 为 &lt;html&gt;&lt;/html&gt; 
标签 也 是 可 以 有 id 的 : 


div#container 


它 会 被 转换 为 &lt;div id="container"&gt;&lt;/div&gt; 
رع‎ 


怎么 加 类 呢 ? 


div.user-details 


转换 为 &lt;div class-"user-details"&gt;&lt;/div&gt; 
多 个 类 ? 和 id? 也 是 可 以 搞定 的 : 
div#foo.bar.baz 
转换 为 &lt;div id="foo" class="bar baz"&gt;&lt;/div&gt; 
MEAN div div div 很 讨厌 啊 , 可 以 这 让 


Zfoo 
.bar 


这 个 算是 我 们 的 语法 糖 ， 它 已 经 被 很 好 的 支持 了 ， 上 面 的 会 输出 : 


<div id="foo"></div><div class="bar"></div>. 


标签 文本 
只 需要 简单 的 把 内 容 放 在 标签 之 后 


wahoo!‏ م 


CAMERA &lt;p&gt;wahoo!&lt;/pagt; 
4R Jp OE, 但 是 大 段 的 文本 怎么 办 呢 。 


foo bar baz 
rawr rawr 

super cool 
go jade go 


泻 染 为 &lt;p&gt;foo bar baz rawr..... &lt;/p&gt; 


怎么 和 数据 结合 起 来 ? 所 有 类 型 的 文本 展示 都 可 以 和 数据 结合 起 来 ， 如 果 我 们 
把 { name: 'tj', email: 'tj@vision-media.ca' ( 传 给 编译 男 数 ， 下 面 是 模 
板 上 的 写法 : 


#user #{name} &lt;#{email}&gt; 


CAMERA 
&lt;div id="user"&gt;tj &1t;tjQvision-media.ca&gt;&lt;/div&gt; 
当 就 是 要 输出 #{} 的 时 候 怎么 办 ? 转 义 一 下 ! 
م‎ \#{something} 
它 会 输出 &lt;p&gt;4(something)&lt;/p&gt; 


同 祥 可 以 使 用 非 转 义 的 变量 !{html} , 下 面 的 模板 将 直接 输出 一 个 script 标 签 


- var html = "<script></script>" 
| ! {html} 


内 联 标签 同样 可 以 使 用 文本 块 来 包含 文本 : 


label 
| Username: 
input (name='user[name]' ( 


或 者 直接 使 用 标签 文本 : 


label Username: 
input (name='user[name]' ( 


只 包含 文本 的 标签 ， 比 如 script , style ,和 textarea 不 需要 前 级 | FF, 
比如 : 


html 
head 
title Example 
script 
if (foo) { 
bar(); 
} else 1 
baz(); 
} 


这 里 还 有 一 种 选择 ， 可 以 使 用 . 来 开始 一 段 文本 块 ， 比 如 : 


De 
foo asdf 
asdf 

asdfasdfaf 
asdf 
asd. 


<p>foo asdf 
asdf 
asdfasdfaf 
asdf 
asd 


</p> 


这 和 带 一 个 空格 的 … 是 不 一 样 的 , 带 空 格 的 会 被 Jade 的 解析 器 忽略 ， 当 作 一 个 普通 
的 文字 : 


<p>.</p> 


需要 注意 的 是 广西 块 需要 两 次 转 义 。 比 如 想 要 输出 下 面 的 文本 : 


</p>foo\bar</p> 


使 用 : 


p. 
fooNNbar 


注释 
单行 注释 和 JavaScript 里 是 一 样 的 ， 通 过 "//" 来 开始 ， 并 且 必 须 单 独 一 行 : 
// just some paragraphs 


p foo 
p bar 


<!-- just some paragraphs --> 
<p>foo</p> 
<p>bar</p> 


Jade 同样 支持 不 输出 的 注释 ， 加 一 个 短 横 线 就 行 了 : 


//- will not output within markup 
p foo 
p bar 


<p>foo</p> 
<p>bar</p> 


块 注释 
块 注释 也 是 支持 的 : 
body 
// 


#content 
h1 Example 


<body> 
eae 
<div id="content"> 
<hi>Example</h1> 
</div> 
ees 
«/body» 


Jade 同样 很 好 的 支持 了 条 件 注 释 : 


body 
//if IE 
a(href='http://www.mozilla.com/en-US/firefox/') Get Firefox 


Jade SHU BANARE SL HRS: 


ul 
li.first 
a(href='#') foo 
li 
a(href='#') bar 
li.last 
a(href='#') baz 


RRA 
块 展开 可 以 帮助 你 在 一 行内 创建 谋 套 的 标签 ， 下 面 的 例子 和 上 面 的 是 一 样 的 : 


ul 
li.first: a(href='#') foo 
li: a(href='#') bar 
li.last: a(href='#') baz 
属性 
Jade 现在 支持 使 用 '( 和 ') 作为 属性 分 隔 符 


a(href='/login', title-'View login page') Login 


当 一 个 值 是 undefined 或 者 null 属性 不 会 被 加 上 , 所 以 呢 ， 它 不 会 编译 出 
‘something="null". 


div(something-null) 


Boolean 属性 也 是 支持 的 : 


input(type="checkbox", checked) 


使 用 代码 的 Boolean 属性 只 有 当 属 性 为 true 时 才 会 输出 : 


input (type="checkbox", checked-someValue) 


多 行 同样 也 是 可 用 的 : 


input (type='checkbox', 
name='agreement', 
checked) 


多 行 的 时 候 可 以 不 加 逗号 : 


input(type="'checkbox' 
name-'agreement ' 
checked) 


加 点 空格 ， 格 式 好 看 一 点 ? [BH 


input ( 
type='checkbox' 
name-'agreement ' 
checked) 


冒号 也 是 支持 的 : 


rss(xmlns:atom="atom") 


假如 我 有 一 个 user 对 象 { id: 12, name: 'tobi' } 我 们 希望 创建 一 个 指 
向 "/user/12" 的 链接 href ,我 们 可 以 使 用 普通 的 javascript 字 符 串 连接 ， 如 下 : 


a(href='/user/' + user.id)= user.name 


或 者 我 们 使 用 jade 的 修改 方式 ,这 个 我 想 很 多 使 用 Ruby 或 者 CoffeeScript 的 人 会 看 起 
来 像 普 通 的 js.…: 


a(href='/user/#{user.id}')= user.name 


class 属性 是 一 个 特殊 的 属性 ， 你 可 以 直接 传递 一 个 数组 ， 比 


如 bodyClasses = ['user', 'authenticated'] 


body(class=bodyClasses ) 


HTML 
内 联 的 html 是 可 以 的 ， 我 们 可 以 使 用 管道 定义 一 段 文本 : 
html 
body 
| <hi>Title</h1> 
| <p>foo bar baz</p> 
或 者 我 们 可 以 使 用 . 来 告诉 Jade 我 们 需要 一 段 文本 : 
html 
body. 


<hi>Title</h1> 
<p>foo bar baz</p> 


上 面 的 两 个 例子 都 会 泻 染 成 相同 的 结果 : 


<html><body><h1>Title</h1> 
<p>foo bar baz</p> 
«/body»«/html» 


这 条 规则 适应 于 在 jade 里 的 任何 文本 : 


html 
body 
hi User <em>#{name}</em> 


Doctypes 
添加 文档 类 型 只 需要 简单 的 使 用 11! ,或 者 doctype 跟 上 下 面 的 可 选项 : 


FE transitional 文档 类 型 , 或 者 : 


Eo 


!!! html 
Or 


doctype html 


doctypes 是 大 小 写 不 敏感 的 , 所 以 下 面 两 个 是 一 样 的 : 


doctype Basic 
doctype basic 


当然 也 是 可 以 直接 传递 一 段 文档 类 型 的 文本 : 


doctype html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN 


juif 
x 
um 


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN> 


会 输出 html 5 文档 类 型 . 下 面 的 默认 的 文档 类 型 ， 可 以 很 简单 的 扩展 : 


var doctypes = exports.doctypes = 1 

'5': '«IDOCTYPE html»', 

'xml': '«?xml version="1.0" encoding="utf-8" ?>', 
'default': '«!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 T! 
'transitional': '«!DOCTYPE html PUBLIC "-//W3C//DTD XHTML : 
'strict': '«!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Sti 
'frameset': '«!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 I 
'1.1': '«!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" ' 
'basic': '«!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1 
'mobile': '«!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mc 
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通过 下 面 的 代码 可 以 很 简单 的 改变 默认 的 文档 类 型 : 


jade.doctypes.default = ‘whatever you want'; 
`~ ` 口 
it has 


过 滤器 前 级 : ,比如 :markdown 会 把 下 面 块 里 的 文本 交 给 专门 的 函数 进行 处 
理 。 查 看 顶部 特性 里 有 哪些 可 用 的 过 滤器 。 


body 
:markdown 
Woah! jade and markdown, very **cool** 
we can even link to [stuff](http://google.com) 


<body><p>Woah! jade <em>and</em> markdown, very <strong>cool</str¢ 


[t] [um expe 


代码 


Jade 目 前 支持 三 种 类 型 的 可 执行 代码 。 第 一 种 是 前 级 - ， 这 是 不 会 被 输出 的 : 





- var foo = 'bar'; 


这 可 以 用 在 条 件 语句 或 者 循环 中 : 





- for (var key in obj) 
p= obj [key] 


由 于 Jade 的 缓存 技术 ， 下 面 的 代码 也 是 可 以 的 : 


- if (foo) 


11 worked 
- else 
p oh no! didnt work 


哈哈 ， 其 至 是 很 长 的 循环 也 是 可 以 的 : 


- if (items.length) 


ul 
- items.forEach(function(item)( 
li- item 
zu) 


一 步 我 们 要 转 义 输出 的 代码 ， 上 比如 我 们 返回 一 个 值 ， 只 要 前 弘一 个 = 


- var foo = 'bar' 
= foo 
hi= foo 


它 会 泻 染 为 bar&lt;hi&gt;bar&lt;/hi&gt; .为 了 安全 起 见 ， 使 用 = 输出 的 代 
码 默 认 是 转 义 的 ， 如 果 想 直接 输出 不 转 义 的 值 可 以 使 用 != 


p!= aVarContainingMoreHTML 


Jade 同 祥 是 设计 病友 好 的 ， 它 可 以 使 javascript 更 直接 更 富 表 现 力 。 比 如 下 面 的 赋 
值 语句 是 相等 的 ， 同 时 表达 式 还 是 通常 的 javascript : 


- var foo = 'foo ' + 'bar' 
foo = foo ' + pares 


Jade 会 把 if ب‎ else 2T , else , until , while , unless 同 别 的 优先 对 待 ， 
但 是 你 得 记 住 它 TRES 通 的 javascript : 


它们 可 以 让 


if foo == 'bar' 
ul 
li yay 
11 foo 
11 worked 
else 
p oh no! didnt work 


循环 


尽管 已 经 支持 JavaScript 原 生 代 码 ，Jade 还 是 支持 了 一 些 特殊 的 标签 ， 


模板 更 加 易于 理解 ， 其 中 之 一 就 是 each ， 这 种 形式 : 
each VAL[, KEY] in 3 


一 个 通 历 数组 的 例子 : 


- var items = ["one", "two", "three"] 
each item in items 
li- item 


N 
N 
/ 


[mir 


RA: 


<li>one</1li> 
<li>two</li> 
<li>three</li> 


通 历 一 个 数组 同时 带 上 索引 : 


items = ["one", "two", "three"] 
each item, i in items 
li #{item}: #{i} 


泻 染 为 : 


<li>one: 0«/li» 
<li>two: 1«/li» 
<li>three: 2«/li» 


通 历 一 个 数组 的 键 值 : 


obj = { foo: 'bar' } 
each val, key in obj 
li #{key}: #{val} 


将 会 泻 染 为 : &lt;li&gt;foo: bar&lt;/liagt; 


Jade 在 内 部 会 把 这 些 语句 转换 成 原生 的 JavaScript 语 句 ， 就 像 使 用 
users.forEach(function(user){ ,词法 作用 域 和 旋 套 会 像 在 普通 的 JavaScript 
中 一 样 : 


each user in users 
each role in user.roles 
li- role 


如 果 你 喜欢 ， 也 可 以 使 用 for 


for user in users 
for role in user.roles 
li- role 


条 件 语 句 


Jade 条 件 语句 和 使 用 了 ( - ) 前 级 的 JavaScript 语 句 是 一 致 的 ,然后 它 人 允许 你 不 使 用 
圆 括 号 ， 这 样 会 看 上 去 对 设计 病 更 友好 一 点 ， 同时 要 在 心里 记 住 这 个 表达 式 泻 染 出 
的 是 常规 _Javascript : 


for user in users 
if user.role == 'admin' 
p #{user.name} is an admin 
else 
p= user.name 


和 下 面 的 使 用 了 常规 JavaScript 的 代码 是 相等 的 : 


for user in users 


- if (user.role == 'admin' ) 
p #{user.name} is an admin 
- else 


p= user.name 


Jade 同时 支持 unless ,这 和 if (!(expr)) 是 等 价 的 : 


for user in users 
unless user.isAnonymous 


| Click to view 
a(href='/users/' + user.id)= user.name 


模板 继承 


Jade 支持 通过 block 和 extends 关键 字 来 实现 模板 继承 。 一 个 块 就 是 一 个 
Jade 的 "block" ， 它 将 在 子 模板 中 实现 ， 同 时 是 支持 递 愉 的。 


Jade 块 如 果 没 有 内 容 ，Jade 会 添加 默认 内 容 ， 下 面 的 代码 默认 会 输 
出 block scripts , block content ,和 block foot . 


html 
head 
hi My Site - #{title} 
block scripts 
script(src='/jquery.js') 
body 
block content 
block foot 
#footer 
p some footer content 


现在 我 们 来 继承 这 个 布局 ， 简 单 创建 一 个 新 文件 ， 像 下 面 那样 直接 使 

用 extends ， 给 定 路 径 (可 以 选择 带 .jade 扩 展 名 或 者 不 带 ). 你 可 以 定义 一 个 或 
者 更 多 的 块 来 覆盖 父 级 块 内 容 , 注意 到 这 里 的 foot 块 没有 定义 ， 所 以 它 还 会 输出 
父 级 的 "some footer content"。 


extends extend-layout 


block scripts 
script(src='/jquery.js') 
script(src='/pets.js') 


block content 
hi= title 
each pet in pets 
include pet 


同样 可 以 在 一 个 子 块 里 添加 块 ， 就 像 下 面 实现 的 块 content 里 又 定义 了 两 个 可 以 
被 实现 的 块 sidebar 和 primary ， 或 者 子 模板 直接 实现 content o 


extends regular-layout 


block content 
. Sidebar 
block sidebar 
p nothing 
. primary 
block primary 
p nothing 


ae 


Includes 人 允许 你 静态 包含 一 段 Jade, 或 者 别 的 存放 在 单个 文件 中 的 东西 比如 css， 
html, 非常 常见 的 例子 是 包含 头 部 和 页 脚 。 假设 我 们 有 一 个 下 面目 录 结 构 的 文件 
夹 : 


./layout.jade 

./includes/ 
./head. jade 
./tail.jade 


下 面 是 layoutjade 的 内 容 : 


html 
include includes/head 
body 
hi My Site 
p Welcome to my super amazing site. 
include includes/foot 


这 两 个 包含 includes/head 和 includes/foot 都 会 读 取 相 对 于 给 layout.jade & 

数 filename 的 路 径 的 文件 , 这 是 一 个 绝对 路 径 ， 不 用 担心 Express 帮 你 搞定 这 些 
T. Include 会 解析 这 些 文件 ， 并 且 插 入 到 已 经 生成 的 语法 树 中 ， 然 后 泻 染 为 你 期 
待 的 内 容 : 


<html> 
<head> 
<title>My Site</title> 
<script src="/javascripts/jquery.js"> 
</script><script src="/javascripts/app.js"></script> 
</head> 
<body> 
<hi>My Site</hi> 
«p»Welcome to my super lame site.</p> 
«div id="footer"> 
<p>Copyright>(c) foobar</p> 
</div> 
</body> 
</html> 


前 面 已 经 提 到 ， include 可 以 包含 比如 html 或 者 css 这 样 的 内 容 。 给 定 一 个 扩展 
名 后 ，Jade 不 会 把 这 个 文件 当 作 一 个 Jade 源 代码 ， 并 且 会 把 它 当 作 一 个 普通 文本 包 
含 进来 : 


html 
body 
include content.html 


Include 也 可 以 接受 块 内 容 ， 给 定 的 块 将 会 附加 到 包含 文件 最 后 的 块 里 。 举 个 例 
f, head.jade 包含 下 面 的 内 容 : 


head 
script(src='/jquery.js') 


我 们 可 以 像 下 面 给 include head 添加 内 容 , 这 里 是 添加 两 个 脚本 . 


html 
include head 
script(src='/foo.js') 
script(src='/bar.js') 
body 
hi test 


Mixins 


Mixins 在 编译 的 模板 里 会 被 Jade 转 换 为 普通 的 JavaScript 函 数 。 Mixins 可 以 还 参 
数 ， 但 不 是 必需 的 : 


mixin list 
ul 
11 foo 
11 bar 
li baz 


使 用 不 带 参 数 的 mixin 看 上 去 非常 简单 ， 在 一 个 块 外 : 


h2 Groceries 
mixin list 


Mixins 也 可 以 带 一 个 或 者 多 个 参数 ， 参 数 就 是 普通 的 javascripts 表 达 式 ， 比 如 下 面 


的 例子 : 
mixin pets(pets) 
ul.pets 
- each pet in pets 
li- pet 


mixin profile(user) 
„user 
h2= user.name 
mixin pets(user.pets) 


会 输出 像 下 面 的 html : 


<div class="user"> 
<h2>tj</h2> 
<ul class="pets"> 
<li>tobi</li> 
<li>loki</1li> 
<li>jane</li> 
<li>manny</1i> 
</ul> 
</div> 


产生 输出 
假设 我 们 有 下 面 的 Jade 源 码 : 


- var title = 'yay' 
hi.title #{title} 
p Just an example 


当 compileDebug 选项 不 是 false , Jade 会 编译 时 会 把 函数 里 加 上 
_ .lineno = n; pos a mes rethrow() ,而 这 个 画 数 会 
在 Jade 初 始 输 出 时 给 一 个 有 用 的 错 误 信 息 وكام‎ 


function anonymous(locals) { 


var | = { lineno: 1, input: "- var title = 'yay'Mnhi.title #{til 
var rethrow = jade.rethrow; 
try 1 


var attrs = jade.attrs, escape = jade.escape; 
var buf = []; 
with (locals || {}) 1 
var interp; 
. .lineno = 1; 
var title - 'yay' 
. .lineno = 2; 
buf.push('«h1'); 
buf.push(attrs(( "class": ('title') })); 
buf.push('»'); 
buf.push('' + escape((interp = title) == null ? '' : interp) 
buf.push('«/h1»'); 
. .lineno = 3; 
buf.push('«p»'); 
buf.push('Just an example'); 
buf.push('«/p»'); 


return buf.join(""); 
) catch (err) ( 
rethrow(err, __.input, __.filename, __.lineno); 





“4 compileDebug 参数 是 false ,这 个 参数 会 被 去 掉 ， 这 样 对 于 轻 量 级 的 浏览 器 
端 模板 是 非常 有 用 的 。 حر‎ e ./runtime.js 文件 ， 

你 可 以 通过 toString() 来 编译 模板 而 不 需要 在 浏览 器 端 运行 整个 Jade 库 ， 这 样 可 以 提 
高 性 能 ， 也 可 以 减少 载 和 的 JavaScript 数 量 。 


function anonymous(locals) { 
var attrs = jade.attrs, escape = jade.escape; 
var buf = []; 
with (locals || {}) 1 
var interp; 
var title = 'yay' 
buf.push('«h1'); 
buf.push(attrs({ "class": ('title') })); 
buf.push('»'); 
buf.push('' + escape((interp - title) -- null 2 '' : interp) + 
buf.push('«/h1»'); 
buf.push('«p»'); 
buf.push('Just an example'); 
buf.push('«/p»'); 


return buf.joan(""); 





Makefile 的 一 个 例子 


通过 执行 make , 下 面 的 Makefile 例 子 可 以 把 pages/*.jade 编译 为 pages/*.html 


= $(shell find pages/*.jade) 
= $( JADE: .jade=.htm1) 


all: $(HTML) 


%. html: %.jade 
jade < $< --path $< > $@ 


clean: 
rm -f $(HTML) 


.PHONY: clean 


这 个 可 以 和 watch(1) 命令 起 来 产生 像 下 面 的 行为 : 


$ watch make 


命令 行 的 jade(1) 


使 用 : jade [options] [dir|file ...] 


选项 
-h, --help 全 出 帮助 信息 
-V, --version 输出 版 本 号 
-0, --0bj «str» javascript 选 项 


-0, --out <dir> 输出 编译 后 的 html 到 <dir> 
-p，--path «path» 在 处 理 stdio 时 ， 查 找 包 含 文件 时 的 查找 路 径 


Examples: 


# 编译 整个 目录 
$ jade templates 


# 生成 {foo,bar}.html 
$ jade {foo, bar}.jade 


# 在 标准 I0 下 使 用 jade 
$ jade < my.jade > my.html 


# 在 标准 I0 下 使 用 jade， 同 时 指定 用 于 查找 包含 的 文件 
$ jade < my.jade -p my.jade > my.html 


# 在 标准 I0 下 使 用 jade 
$ echo "hi Jade!" | jade 


# foo, bar 目录 演 染 到 /tmp 
$ jade foo bar --out /tmp 


License 


(The MIT License) 
Copyright (c) 2009-2010 TJ Holowaychuk <tj@vision-media.ca> 


Permission is hereby granted, free of charge, to any person obtaining a copy of 
this software and associated documentation files (the 'Software"), to deal in the 
Software without restriction, including without limitation the rights to use, copy, 
modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, 
and to permit persons to whom the Software is furnished to do so, subject to the 
following conditions: 


The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software. 


THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE 
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 


PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS 
OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR 
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 
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